home *** CD-ROM | disk | FTP | other *** search
Text File | 1998-10-20 | 62.4 KB | 1,321 lines
iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) NNNNAAAAMMMMEEEE iiiiffffllllFFFFiiiilllleeee - abstraction for image file access IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM This is a base class HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE #include <il/iflFile.h> CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN iflFile is an abstraction of a handle to an image file. It is an abstract base class; every iflFile object is actually an object of a file-format-specific subclass such as iflTIFFFile. CCCCrrrreeeeaaaattttiiiinnnngggg aaaannnndddd ddddeeeessssttttrrrrooooyyyyiiiinnnngggg An IFL application opens a file by calling iiiiffffllllFFFFiiiilllleeee::::::::ooooppppeeeennnn() (to open an existing image file) or iiiiffffllllFFFFiiiilllleeee::::::::ccccrrrreeeeaaaatttteeee() (to create a new image file). The returned value is an _i_f_l_F_i_l_e* pointing to a newly created object of the appropriate subclass (one of iflTIFFFile, etc.). The file can be manipulated by calling the object's member functions. The object can be destroyed by calling the cccclllloooosssseeee() member function. Buffered data is automatically flushed during the close(), but the application may elect to explicitly flush at any time by calling fffflllluuuusssshhhh(). This is the only public interface to construction and destruction of iflFile objects. There is no public constructor or destructor for this class or any of its subclasses. It is illegal to create an iflFile on the stack. AAAAcccccccceeeessssssssiiiinnnngggg iiiimmmmaaaaggggeeee ddddaaaattttaaaa Several member functions are used by an IFL application to read image data from an image file into memory, or to write image data from memory to an image file. The most general and usual interface is to use ggggeeeettttTTTTiiiilllleeee() and sssseeeettttTTTTiiiilllleeee(), which allow reading and writing of arbitrary rectangular regions (_t_i_l_e_s), with an arbitrary data type, dimension ordering, and orientation. Optimized applications may want to use the lower-level ggggeeeettttPPPPaaaaggggeeee() and sssseeeettttPPPPaaaaggggeeee() interface, which does no conversion and requires the specified region to be one of the file's natural _p_a_g_e_s. The IFL library implements ggggeeeettttTTTTiiiilllleeee() and sssseeeettttTTTTiiiilllleeee() in terms of ggggeeeettttPPPPaaaaggggeeee() and sssseeeettttPPPPaaaaggggeeee(), which are defined by the format-specific subclasses of iflFile. PPPPaaaaggggeeee 1111 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) AAAAcccccccceeeessssssssiiiinnnngggg ssssuuuubbbb----iiiimmmmaaaaggggeeeessss An image file can contain more than one image, depending on the file format. For example, the TIFF and GIF formats allow a file to contain any number of unrelated images, and the Kodak Photo CD Image Pac (PCD) and JFIF formats allow access to multiple resolutions of the same image. Both of these situations are handled by the notion of an iflFile object's "current image index". Image operations and queries applied to an iflFile object refer to the image at the current index. The application can change the index by calling the object's sssseeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg() method. The current index and total number of images in the file can be queried by calling the ggggeeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg() or ggggeeeettttNNNNuuuummmmIIIImmmmggggssss() method, respectively. The initial index may also be set by specifying an index with the filename argument to iiiiffffllllFFFFiiiilllleeee::::::::ooooppppeeeennnn() (see the description of that function above). Note that these operations are meaningful even if the file format does not support multiple images per file. In that case, ggggeeeettttNNNNuuuummmmIIIImmmmggggssss() returns 1, ggggeeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg() returns 0, and sssseeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg(idx) will succeed if and only if idx == 0. If an image file is open for write access and the file format and format-specific implementation supports it, the application can append an image to an image file by calling the aaaappppppppeeeennnnddddIIIImmmmgggg() member function. IIIICCCCCCCC pppprrrrooooffffiiiilllleeeessss An ICC (International Color Consortium) profile can be used for color management; see _h_t_t_p://_w_w_w._c_o_l_o_r._o_r_g for more details on the specifics of how such profiles are used. To access the profile for those formats that support it, call ggggeeeettttIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee(). When you are done with the profile call ffffrrrreeeeeeeeIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee() to release any allocated memory. You can update the profile of an image by calling sssseeeettttIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee(). The GIF, TIFF, JFIF and SGI formats included with IFL all support ICC profiles. New formats must implement the virtual methods listed above in order to provide ICC profile support. FFFFoooorrrrmmmmaaaatttt----ssssppppeeeecccciiiiffffiiiicccc ooooppppeeeerrrraaaattttiiiioooonnnnssss The member functions ggggeeeettttIIIItttteeeemmmm() and sssseeeettttIIIItttteeeemmmm() deal with "items"; that is, format-dependent name-value pairs associated with an image within an image file. Usage of these functions requires format-specific knowledge of the meaning of the tags for the specific file format; e.g. for iflTIFFFile, the meaning of the tags is given in the TIFF spec. DDDDeeeeaaaalllliiiinnnngggg wwwwiiiitttthhhh ccccoooonnnnccccuuuurrrrrrrreeeennnntttt aaaacccccccceeeesssssssseeeessss If an IFL application is going to make concurrent calls to an iflFile's ggggeeeettttPPPPaaaaggggeeee() and/or sssseeeettttPPPPaaaaggggeeee() methods, it must provide the iflFile object PPPPaaaaggggeeee 2222 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) with a semaphore mechanism. The application does this by supplying a beginFileIO callback with sssseeeettttBBBBeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB() (which should acquire a semaphore) and an endFileIO callback with sssseeeettttEEEEnnnnddddFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB() (which should release the semaphore). These callbacks will be called by ggggeeeettttPPPPaaaaggggeeee() and sssseeeettttPPPPaaaaggggeeee() surrounding thread-unsafe code. See the next section for the DSO implementor's interface to this mechanism. DDDDEEEERRRRIIIIVVVVIIIINNNNGGGG SSSSUUUUBBBBCCCCLLLLAAAASSSSSSSSEEEESSSS iflFile subclass implementors must surround code that needs to be executed atomically with calls to the protected bbbbeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO() and eeeennnnddddFFFFiiiilllleeeeIIIIOOOO() member functions (which call the application's beginFileIO and endFileIO callbacks, respectively, if they exist). The most common and unavoidable case is when getPage or setPage contain an llllsssseeeeeeeekkkk() and a subsequent rrrreeeeaaaadddd() or wwwwrrrriiiitttteeee(); this code must be surrounded by bbbbeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO()/eeeennnnddddFFFFiiiilllleeeeIIIIOOOO() to insure that concurrent calls don't change the I/O pointer between the seek and the read or write. If the underlying sssseeeettttPPPPaaaaggggeeee()/ggggeeeettttPPPPaaaaggggeeee() code is completely non-MP-safe, the implementor may choose to surround the entire function bodies with bbbbeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO()/eeeennnnddddFFFFiiiilllleeeeIIIIOOOO(). CCCCrrrreeeeaaaattttiiiinnnngggg aaaannnndddd ddddeeeessssttttrrrrooooyyyyiiiinnnngggg The IFL library's functions ooooppppeeeennnn()/ccccrrrreeeeaaaatttteeee()/cccclllloooosssseeee() methods call the ooooppppeeeennnnFFFFiiiilllleeee()/ccccrrrreeeeaaaatttteeeeFFFFiiiilllleeee()/cccclllloooosssseeeeFFFFiiiilllleeee() protected virtual functions to perform the subclass-specific initialization and destruction of an iflFile object. These functions are not accessible to the application. If you install ifl_dev.sw.gifts then you can check out the source code provided in /usr/share/src/ifl for more examples of deriving from iflFile. CCCCLLLLAAAASSSSSSSS MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN SSSSUUUUMMMMMMMMAAAARRRRYYYY CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr iflFile() _p_r_o_t_e_c_t_e_d OOOOppppeeeennnn////ccccrrrreeeeaaaatttteeee////cccclllloooosssseeee mmmmeeeetttthhhhooooddddssss static iflFile* open(iflFileDesc& fileDesc, int mode = O_RDONLY, iflStatus* status=NULL) static iflFile* open(int fd, const char* filename, int mode=O_RDONLY, iflFormat* format=NULL, iflStatus* status=NULL) static iflFile* open(const char* filename, int mode = O_RDONLY, iflStatus* status=NULL) static iflFile* create(iflFileDesc& fileDesc, iflFile* source, const iflFileConfig* cfg=NULL, PPPPaaaaggggeeee 3333 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) iflStatus* status=NULL) static iflFile* create(int fd, const char *filename, iflFile* source, const iflFileConfig* cfg=NULL, iflFormat* format=NULL, iflStatus* status=NULL) static iflFile* create(const char *filename, iflFile* source, const iflFileConfig* cfg=NULL, iflFormat* format=NULL, iflStatus* status=NULL) iflStatus close(int flags = 0) virtual iflStatus flush() static char* parseFileName(const char* fullname, char** formatName=NULL, int* index=NULL, char** formatArgs=NULL) PPPPuuuubbbblllliiiicccc ffffuuuunnnnccccttttiiiioooonnnnssss ttttoooo ggggeeeetttt////sssseeeetttt iiiimmmmaaaaggggeeee ddddaaaattttaaaa iflStatus getTile(int x, int y, int z, int nx, int ny, int nz, void *data, const iflConfig* config=NULL) iflStatus setTile(int x, int y, int z, int nx, int ny, int nz, const void *data, const iflConfig* config=NULL) virtual iflStatus getPage(void* data, int x, int y, int z, int c, int nx, int ny, int nz, int nc) virtual iflStatus setPage(const void* data, int x, int y, int z, int c, int nx, int ny, int nz, int nc) virtual iflStatus getCompressedPage(...) virtual iflStatus decompressPage(...) virtual iflStatus compressPage(...) virtual iflStatus setCompressedPage(...) MMMMaaaannnniiiippppuuuullllaaaattttiiiinnnngggg tttthhhheeee ccccuuuurrrrrrrreeeennnntttt iiiimmmmaaaaggggeeee iiiinnnnddddeeeexxxx virtual int getNumImgs() virtual int getCurrentImg() virtual iflStatus setCurrentImg(int i) AAAAddddddddiiiinnnngggg iiiimmmmaaaaggggeeeessss virtual iflStatus appendImg(iflFile* source, iflFileConfig* fc=NULL) AAAAttttttttrrrriiiibbbbuuuutttteeee qqqquuuueeeerrrryyyy const char* getFileName() int getFileDesc() int getFileMode() iflFormat* getFormat() iflColorModel getColorModel() int* getChannelPermutation() void getDimensions(iflSize& dimensions) void getSize(iflSize& sz, iflOrientation toOrientation) int getZsize() int getCsize() iflDataType getDataType() PPPPaaaaggggeeee 4444 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) iflOrder getOrder() void getPageDimensions(iflSize& pageDims) void getPageSize(iflSize& sz, iflOrientation toOrientation) iflOrientation getOrientation() iflCompression getCompression() virtual iflStatus getColormap(const iflColormap*& cmap) virtual iflStatus getStatMinMax(double& min, double& max) virtual iflStatus getScaleMinMax(double& min, double& max) iflStatus getItem(int tag, ...) virtual iflStatus getItem(int tag, va_list ap) int haveAttributesChanged() AAAAttttttttrrrriiiibbbbuuuutttteeee sssseeeettttttttiiiinnnngggg virtual iflStatus setColormap(const iflColormap* cmap) virtual iflStatus setStatMinMax(double min, double max) virtual iflStatus setScaleMinMax(double min, double max) iflStatus setItem(int tag, ...) virtual iflStatus setItem(int tag, va_list ap) void setBeginFileIO_CB(iflStatus(*cb)(void*), void* arg) void setEndFileIO_CB(iflStatus(*cb)(void*), void* arg) void markAttributesChanged() _p_r_o_t_e_c_t_e_d FFFFiiiilllleeee aaaarrrrgggguuuummmmeeeennnntttt ppppaaaarrrrssssiiiinnnngggg int parseArguments(iflParameterDesc* params, int maxParams) _p_r_o_t_e_c_t_e_d static int lookupName(const char* name, const iflNameDesc* names)_p_r_o_t_e_c_t_e_d MMMMuuuullllttttiiii----pppprrrroooocccceeeessssssssiiiinnnngggg pppprrrrooootttteeeeccccttttiiiioooonnnn iflStatus beginFileIO() _p_r_o_t_e_c_t_e_d iflStatus endFileIO() _p_r_o_t_e_c_t_e_d IIIICCCCCCCC pppprrrrooooffffiiiilllleeee aaaacccccccceeeessssssss virtual iflStatus getICCProfile(int& size, void*& profile) virtual iflStatus freeICCProfile(void* profile) virtual iflStatus setICCProfile(int size, const void* profile) FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS iiiiffffllllFFFFiiiilllleeee(((()))) iflFile() _p_r_o_t_e_c_t_e_d The protected default constructor, called implicitly in derived- class constructors, initializes itself to an empty state. PPPPaaaaggggeeee 5555 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) aaaappppppppeeeennnnddddIIIImmmmgggg(((()))) virtual iflStatus appendImg(iflFile* source, iflFileConfig* fc=NULL) This virtual member function appends an image to the image file, and sets the current image index to the index of the new (last) image. The _s_o_u_r_c_e and _c_f_g parameters are treated the same as in the _c_r_e_a_t_e() static member function. On success, the function returns iflOKAY. If the operation fails for some reason, an IFL error will be thrown via the iiiiffffllllEEEErrrrrrrroooorrrr() mechanism, and the file's contents and the object's current index will be in an unknown state. bbbbeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO(((()))) iflStatus beginFileIO() _p_r_o_t_e_c_t_e_d Calls the beginFileIO callback that was set by the application by a previous call to sssseeeettttBBBBeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB(), and returns the returned value. If no callback was set, just returns iflOKAY. cccclllloooosssseeee(((()))) iflStatus close(int flags = 0) This member function flushes any buffered data to the file referred to by the object (unless _I_F_L__C_L_O_S_E__D_I_S_C_A_R_D is specified in the flags argument), closes the file, and destroys the object. This is the only way for the application to destroy an iflFile object (there is no public destructor). Note that the file descriptor will be closed even if it was opened prior to the original iiiiffffllllFFFFiiiilllleeee::::::::ooooppppeeeennnn() or iiiiffffllllFFFFiiiilllleeee::::::::ccccrrrreeeeaaaatttteeee(). If the caller wants to keep the file descriptor open, it must dddduuuupppp() the file descriptor beforehand and use the resulting file descriptor as the argument to the original iiiiffffllllFFFFiiiilllleeee::::::::ooooppppeeeennnn() or iiiiffffllllFFFFiiiilllleeee::::::::ccccrrrreeeeaaaatttteeee(). Then _f_l_a_g_s parameter is the bitwise "or" of zero or more of the following: _I_F_L__C_L_O_S_E__D_I_S_C_A_R_D The default behavior is to call the fffflllluuuusssshhhh() member function before closing the file. This flag suppresses that call. All three operations (flushing, closing, destroying the object) are performed regardless of whether any of them returns failure. If an error is returned from any of them, the first such error value will PPPPaaaaggggeeee 6666 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) be returned up the caller; otherwise iflOKAY will be returned. ccccoooommmmpppprrrreeeessssssssPPPPaaaaggggeeee(((()))) virtual iflStatus compressPage(...) This method is part of IFL's intended future support for for per- page compression and decompression of image data. It is currently unsupported. ccccrrrreeeeaaaatttteeee(((()))) static iflFile* create(const char *filename, iflFile* source, const iflFileConfig* cfg=NULL, iflFormat* format=NULL, iflStatus* status=NULL) static iflFile* create(int fd, const char *filename, iflFile* source, const iflFileConfig* cfg=NULL, iflFormat* format=NULL, iflStatus* status=NULL) static iflFile* create(iflFileDesc& fileDesc, iflFile* source, const iflFileConfig* cfg=NULL, iflStatus* status=NULL) This static class member function creates a new image file with the specified name and attributes. The _f_i_l_e_n_a_m_e argument specifies the file name of the file to be created. An existing file descriptor may be given additionally or instead using the _f_d parameter, exactly as for ooooppppeeeennnn(). The _f_o_r_m_a_t argument specifies the desired output format. If this argument is NULL, a format is selected by the file typing rules using the filename's extension. If no match is found, the format iiiiffffllllFFFFoooorrrrmmmmaaaatttt::::::::ffffiiiinnnnddddBBBByyyyFFFFoooorrrrmmmmaaaattttNNNNaaaammmmeeee("TIFF") is used by default. The alternate form taking a _f_i_l_e_D_e_s_c argument, encapsulates the _f_d, _f_i_l_e_n_a_m_e and _f_o_r_m_a_t arguments in this single argument. See iflFileDesc(3) for more details. The new image file's dimensions, data type, dimension order, color model, orientation, compression, and page dimensions may be specified using the _c_f_g parameter; if not, they are copied from the _s_o_u_r_c_e iflFile* if one was given (as described below) or defaulted to the format's "preferred" value for the respective parameter. When an existing _s_o_u_r_c_e iflFile* is specified; any parameters not specified in the _c_f_g parameter will be copied from this source iflFile (if the value is supported by the destination format) or heuristically selected to be a supported value most suitable for copying data from the source iflFile*. PPPPaaaaggggeeee 7777 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) On successful completion, the function returns a pointer to a newly-created object of the appropriate subclass of iflFile, which the application should eventually destroy using its cccclllloooosssseeee() method. On failure, the function returns NULL and, if the _s_t_a_t_u_s argument is non-NULL, sets the pointed-to iflStatus value to the appropriate error value. ddddeeeeccccoooommmmpppprrrreeeessssssssPPPPaaaaggggeeee(((()))) virtual iflStatus decompressPage(...) This method is part of IFL's intended future support for for per- page compression and decompression of image data. It is currently unsupported. eeeennnnddddFFFFiiiilllleeeeIIIIOOOO(((()))) iflStatus endFileIO() _p_r_o_t_e_c_t_e_d Calls the endFileIO callback that was set by the application by a previous call to sssseeeettttEEEEnnnnddddFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB(), and returns the returned value. If no callback was set, just returns iflOKAY. fffflllluuuusssshhhh(((()))) virtual iflStatus flush() This virtual member function is used to write out any data that is buffered in the iflFile object. It is called automatically by the cccclllloooosssseeee() member function (but this can be overridden, see description of cccclllloooosssseeee() above). It should return iflOKAY on success, or an appropriate iflStatus error value on failure. ffffrrrreeeeeeeeIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee(((()))) virtual iflStatus freeICCProfile(void* profile) The virtual member function frees the profile returned by ggggeeeettttIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee(). ggggeeeettttCCCChhhhaaaannnnnnnneeeellllPPPPeeeerrrrmmmmuuuuttttaaaattttiiiioooonnnn(((()))) int* getChannelPermutation() PPPPaaaaggggeeee 8888 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) This member function returns an array representing the channel permutation of the current image in the image file, or NULL (meaning the identity permutation). It is an array, indexed by memory channel, into the channels stored in the file (as accessed by ggggeeeettttPPPPaaaaggggeeee()/sssseeeettttPPPPaaaaggggeeee()). This should be used by callers of ggggeeeettttPPPPaaaaggggeeee()/sssseeeettttPPPPaaaaggggeeee() to re-order the data. ggggeeeettttCCCCoooolllloooorrrrMMMMooooddddeeeellll(((()))) iflColorModel getColorModel() This member function returns the color model of the current image in the image file. ggggeeeettttCCCCoooolllloooorrrrmmmmaaaapppp(((()))) virtual iflStatus getColormap(const iflColormap*& cmap) Returns the color map associated with the current image in the image file. On successful completion, iflOKAY will be returned and _c_m_a_p will be set to point to a colormap stored in the iflFile object. Note that this colormap cannot be assumed to remain valid across calls to sssseeeettttCCCCoooolllloooorrrrmmmmaaaapppp(), sssseeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg(), aaaappppppppeeeennnnddddIIIImmmmgggg(), cccclllloooosssseeee(), or calls to sssseeeettttIIIItttteeeemmmm() that report modification of the image's attributes. On failure, the return value is an iflStatus encoding the reason for the failure, and the argument _c_m_a_p is undefined. ggggeeeettttCCCCoooommmmpppprrrreeeesssssssseeeeddddPPPPaaaaggggeeee(((()))) virtual iflStatus getCompressedPage(...) This method is part of IFL's intended future support for for per- page compression and decompression of image data. It is currently unsupported. ggggeeeettttCCCCoooommmmpppprrrreeeessssssssiiiioooonnnn(((()))) iflCompression getCompression() Returns the compression method used for the current image in the image file. ggggeeeettttCCCCssssiiiizzzzeeee(((()))) PPPPaaaaggggeeee 9999 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) int getCsize() Returns the number of channels in the current image in the image file. ggggeeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg(((()))) virtual int getCurrentImg() This virtual member function returns the iflFile's current image index, i.e. the index into the list of images or resolutions in the image file, starting at 0. ggggeeeettttDDDDaaaattttaaaaTTTTyyyyppppeeee(((()))) iflDataType getDataType() This member function returns the data type of the current image in the image file. ggggeeeettttDDDDiiiimmmmeeeennnnssssiiiioooonnnnssss(((()))) void getDimensions(iflSize& dimensions) Returns the dimensions (width,height,z,c) of the current image in the image file, expressed with in conventional (x == width, y == height) orientation. ggggeeeettttFFFFiiiilllleeeeDDDDeeeesssscccc(((()))) int getFileDesc() This member function returns the file descriptor used to access the image file. ggggeeeettttFFFFiiiilllleeeeMMMMooooddddeeee(((()))) int getFileMode() This member function returns the access mode by which the file can be accessed. It is _O__R_D_O_N_L_Y, _O__W_R_O_N_L_Y, or _O__R_D_W_R. ggggeeeettttFFFFiiiilllleeeeNNNNaaaammmmeeee(((()))) PPPPaaaaggggeeee 11110000 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) const char* getFileName() This member function returns the file name of the image file, or NULL if the name is unknown (e.g. if the file was opened with a file descriptor only). The returned string points to data within the object, and will become invalid when the object is destroyed. ggggeeeettttFFFFoooorrrrmmmmaaaatttt(((()))) iflFormat* getFormat() Returns a pointer to the file format associated with the file. The pointed-to object is static and valid forever. ggggeeeettttIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee(((()))) virtual iflStatus getICCProfile(int& size, void*& profile) This virtual member function returns the value of the ICC profile associated with the image. The return value is iflOKAY on success, or an appropriate iflStatus error value on failure. ggggeeeettttIIIItttteeeemmmm(((()))) iflStatus getItem(int tag, ...) virtual iflStatus getItem(int tag, va_list ap) Gets the value of an item associated with the current image in the image file. The _t_a_g argument specifies the name of the item to be set; it is interpreted by the specific iflFile subclass. The number and types of the remaining arguments are determined the particular subclass of iflFile and the tag value. The return value is iflOKAY on success, or an appropriate iflStatus error value on failure. The second overloaded form of this method is used by libraries that are passing along a variable calling sequence in _a_p through some wrapper layer. ggggeeeettttNNNNuuuummmmIIIImmmmggggssss(((()))) virtual int getNumImgs() PPPPaaaaggggeeee 11111111 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) This virtual member function returns the number of images contained in the image file. ggggeeeettttOOOOrrrrddddeeeerrrr(((()))) iflOrder getOrder() Returns the dimension order of the current image in the image file. ggggeeeettttOOOOrrrriiiieeeennnnttttaaaattttiiiioooonnnn(((()))) iflOrientation getOrientation() Returns the orientation of the current image in the image file. ggggeeeettttPPPPaaaaggggeeee(((()))) virtual iflStatus getPage(void* data, int x, int y, int z, int c, int nx, int ny, int nz, int nc) This virtual member function reads a page of image data from the image file. The _d_a_t_a argument specifies the address of the memory buffer into which the data should be placed. The arguments _x,_y,_z,_n_x,_n_y and _n_z specify the origin and size of the desired page within the source image file. The caller must guarantee that _n_x,_n_y,_n_z and _n_c are the image's page size and that _x,_y,_z and _c are a multiple of the page size; no checking is done by the function. A successful call to ggggeeeettttPPPPaaaaggggeeee() returns iflOKAY. If an error occurs, an iflStatus value is returned describing the error; in this case the buffer's contents are undefined. If the caller is going to make multiple concurrent calls to ggggeeeettttPPPPaaaaggggeeee() and/or sssseeeettttPPPPaaaaggggeeee(), it needs to set I/O callbacks (see the description of sssseeeettttBBBBeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB(), sssseeeettttEEEEnnnnddddFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB() for how to do this). This function is required to surround code that must be executed atomically by calls to bbbbeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO() and eeeennnnddddFFFFiiiilllleeeeIIIIOOOO() (see the descriptions of these functions for more details and common cases where this is necessary). PPPPaaaaggggeeee 11112222 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) ggggeeeettttPPPPaaaaggggeeeeDDDDiiiimmmmeeeennnnssssiiiioooonnnnssss(((()))) void getPageDimensions(iflSize& pageDims) Returns the natural page dimensions of the current image in the image file, expressed as x == width, y == height. ggggeeeettttPPPPaaaaggggeeeeSSSSiiiizzzzeeee(((()))) void getPageSize(iflSize& sz, iflOrientation toOrientation) Returns the natural page size of the current image in the image file, expressed with respect to the given orientation. ggggeeeettttSSSSccccaaaalllleeeeMMMMiiiinnnnMMMMaaaaxxxx(((()))) virtual iflStatus getScaleMinMax(double& min, double& max) Returns the minimum and maximum value to be used for scaling during color conversion on the current image in the image file. On successful completion, iflOKAY will be returned and the _m_i_n and _m_a_x arguments will be set to the appropriate values. On failure, the return value is an iflStatus encoding the reason for the failure, and the arguments are left unmolested. ggggeeeettttSSSSiiiizzzzeeee(((()))) void getSize(iflSize& sz, iflOrientation toOrientation) Returns the size (x,y,z,c) of the current image in the image file, expressed with respect to the given orientation. Note that the Z and C dimensions (which do not depend on the orientation) can be obtained separately by calling getZSize() and getCSize() respectively. ggggeeeettttSSSSttttaaaattttMMMMiiiinnnnMMMMaaaaxxxx(((()))) virtual iflStatus getStatMinMax(double& min, double& max) Returns the statistical min/max, i.e. the range of values that occur in the current image in the image file. PPPPaaaaggggeeee 11113333 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) On successful completion, iflOKAY will be returned and the _m_i_n and _m_a_x arguments will be set to the appropriate values. On failure, the return value is an iflStatus encoding the reason for the failure, and the arguments are left unmolested. ggggeeeettttTTTTiiiilllleeee(((()))) iflStatus getTile(int x, int y, int z, int nx, int ny, int nz, void *data, const iflConfig* config=NULL) This member function reads an arbitrary rectangular region from the image file into memory. The portions of the memory buffer corresponding to area outside the boundaries of the source file image are left undisturbed. The arguments _x,_y,_z,_n_x,_n_y and _n_z specify the origin and size of the desired tile within the source image file, in the coordinate space indicated in the _c_o_n_f_i_g parameter. The _d_a_t_a argument specifies the address of the memory buffer into which the data should be placed. The _c_o_n_f_i_g argument describes the configuration of the memory buffer, and its orientation also affects the interpretation of _x,_y,_z,_n_x,_n_y and _n_z, as described above. If defaulted, attributes of the buffer are assumed to match those of the image. A successful call to ggggeeeettttTTTTiiiilllleeee() returns iflOKAY. If an error occurs, an iflStatus value is returned describing the error; in this case the buffer's contents are undefined. ggggeeeettttZZZZssssiiiizzzzeeee(((()))) int getZsize() Returns the Z component of the size of the current image in the image file. hhhhaaaavvvveeeeAAAAttttttttrrrriiiibbbbuuuutttteeeessssCCCChhhhaaaannnnggggeeeedddd(((()))) int haveAttributesChanged() Returns TRUE if any image attributes have changed due to a call to sssseeeettttIIIItttteeeemmmm() since last call to this method. llllooooooookkkkuuuuppppNNNNaaaammmmeeee(((()))) PPPPaaaaggggeeee 11114444 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) static int lookupName(const char* name, const iflNameDesc* names) _p_r_o_t_e_c_t_e_d This method can be used to lookup parameter names/values in a list of name/id pairs. The id associated with the first match is returned (abbreviated names are allowed as matches). The names array is terminated with an entry whose associated id is returned if no match is found. mmmmaaaarrrrkkkkAAAAttttttttrrrriiiibbbbuuuutttteeeessssCCCChhhhaaaannnnggggeeeedddd(((()))) void markAttributesChanged() _p_r_o_t_e_c_t_e_d The method is used by a sssseeeettttIIIItttteeeemmmm() implementation to indicate that some above the above core attributes were changed as a side effect. This flag is tested and cleared by calling hhhhaaaavvvveeeeAAAAttttttttrrrriiiibbbbuuuutttteeeessssCCCChhhhaaaannnnggggeeeedddd(). ooooppppeeeennnn(((()))) static iflFile* open(const char* filename, int mode = O_RDONLY, iflStatus* status=NULL) static iflFile* open(int fd, const char* filename, int mode=O_RDONLY, iflFormat* format=NULL, iflStatus* status=NULL) static iflFile* open(iflFileDesc& fileDesc, int mode = O_RDONLY, iflStatus* status=NULL) This static class member function opens an existing image file. The file is specified via the _f_i_l_e_n_a_m_e and _f_d arguments. At least one of these two arguments must be specified; they are interpreted as follows. if filename != NULL and fd == -1: opens the file with the given filename. if filename == NULL and fd != -1: uses the existing open file descriptor. if filename != NULL and fd != -1: uses the existing open file descriptor; the filename is stored solely for the getFileName() method and error messages. The file name may be followed by an optional sub-image index using the syntax "filename:index" (see sssseeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmaaaaggggeeee() for how to change the sub-image index after the file is opened). The mode argument specifies the desired access mode; it should be either _O__R_D_O_N_L_Y or _O__R_D_W_R. The _f_o_r_m_a_t argument specifies the desired file format. The usual usage is to use NULL in which case the file format is deduced by the file typing rules using the file's contents ("magic number"); this PPPPaaaaggggeeee 11115555 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) mechanism can be bypassed by specifying the format explicitly. The alternate form taking a _f_i_l_e_D_e_s_c argument, encapsulates the _f_d, _f_i_l_e_n_a_m_e and _f_o_r_m_a_t arguments in this single argument. See iflFileDesc(3) for more details. On successful completion, the function returns a pointer to a newly-created object of the appropriate subclass if iflFile, which the application should eventually destroy using its cccclllloooosssseeee() method. On failure, the function returns NULL and, if the _s_t_a_t_u_s argument is non-NULL, sets the pointed-to iflStatus value to the appropriate error value. ppppaaaarrrrsssseeeeAAAArrrrgggguuuummmmeeeennnnttttssss(((()))) int parseArguments(iflParameterDesc* params, int maxParams) _p_r_o_t_e_c_t_e_d This method can be used to parse the format specific argument string using a standard <parameter-name>=<parameter-value> syntax where multiple parameters are separated by spaces or '%'. The iflParameterDesc array pointed to by _p_a_r_a_m_s with maximum size _m_a_x_P_a_r_a_m_s will be filled in. The returned value is the number of parameters found. The llllooooooookkkkuuuuppppNNNNaaaammmmeeee() method can be used to assist in decoding parameter names. ppppaaaarrrrsssseeeeFFFFiiiilllleeeeNNNNaaaammmmeeee(((()))) static char* parseFileName(const char* fullname, char** formatName=NULL, int* index=NULL, char** formatArgs=NULL) This static class member function is used to parse a file name for IFL. IFL file names have the following syntax: <file-name>[#<format-name>][:<image-index>][%<format-specific>] The return value is the actual file name and must be delete'd by the user. The format name can be returned via _f_o_r_m_a_t_N_a_m_e if it is non- NULL; if no format name is present in the filename then NULL will be returned. The sub-image index can be returned via _i_n_d_e_x if it is non-NULL; if no index is present in the filename then -1 will be returned. The format specific argument string can be returned via _f_o_r_m_a_t_A_r_g_s if it is non-NULL; if no format specific arguments are present in the filename then NULL will be returned. See ppppaaaarrrrsssseeeeAAAArrrrgggguuuummmmeeeennnnttttssss() for optional support in parsing format specific arguments (recommended for consistency). PPPPaaaaggggeeee 11116666 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) This function is called automatically by the open() member function. sssseeeettttBBBBeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB(((()))) void setBeginFileIO_CB(iflStatus(*cb)(void*), void* arg) Sets the callback and arg that will be called by bbbbeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO() during calls to ggggeeeettttPPPPaaaaggggeeee() and sssseeeettttPPPPaaaaggggeeee(). To disable this callback, use NULL for the _c_b argument. sssseeeettttCCCCoooolllloooorrrrmmmmaaaapppp(((()))) virtual iflStatus setColormap(const iflColormap* cmap) Sets the color map associated with the current image to be a copy of the colormap pointed to by the argument _c_m_a_p. On successful completion, the function returns iflOKAY. On failure, the function returns an iflStatus indicating the reason for failure. Whether or not the function succeeds, the value returned from previous calls to getColormap() becomes invalid. sssseeeettttCCCCoooommmmpppprrrreeeesssssssseeeeddddPPPPaaaaggggeeee(((()))) virtual iflStatus setCompressedPage(...) This method is part of IFL's intended future support for for per- page compression and decompression of image data. It is currently unsupported. sssseeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg(((()))) virtual iflStatus setCurrentImg(int i) This virtual member function sets the current image index (i.e. the index into the list of images or resolutions in the image file, starting at 0) to _i_d_x. If the operation is successful, the value iflOKAY is returned and the image index is changed (which may mean the dimensions and attributes subsequently returned by the get...() methods may be changed). If the argument given is out of bounds of the images in the file, the value iiiiffffllllSSSSttttaaaattttuuuussssEEEEnnnnccccooooddddeeee(iflFILEFINDEXOOB) is returned and the image index is left unchanged. PPPPaaaaggggeeee 11117777 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) If the operation fails for some other reason, an ifl error will be thrown via the iiiiffffllllEEEErrrrrrrroooorrrr() mechanism; if the program continues, and the file's image index may be the old or the new index. sssseeeettttEEEEnnnnddddFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB(((()))) void setEndFileIO_CB(iflStatus(*cb)(void*), void* arg) Sets the callback and arg that will be called by eeeennnnddddFFFFiiiilllleeeeIIIIOOOO() during calls to ggggeeeettttPPPPaaaaggggeeee() and sssseeeettttPPPPaaaaggggeeee(). To disable this callback, use NULL for the _c_b argument. sssseeeettttIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee(((()))) virtual iflStatus setICCProfile(int size, const void* profile) This virtual member function sets the value of the ICC profile associated with the image. The return value is iflOKAY on success, or an appropriate iflStatus error value on failure. sssseeeettttIIIItttteeeemmmm(((()))) iflStatus setItem(int tag, ...) virtual iflStatus setItem(int tag, va_list ap) Sets the value of an item associated with the current image in the image file. Calling sssseeeettttIIIItttteeeemmmm() may change some image attributes. This can be check by calling hhhhaaaavvvveeeeAAAAttttttttrrrriiiibbbbuuuutttteeeessssCCCChhhhaaaannnnggggeeeedddd() after calling sssseeeettttIIIItttteeeemmmm(). The _t_a_g argument specifies the name of the item to be set; it is interpreted by the specific iflFile subclass. The number and types of the remaining arguments are determined the particular subclass of iflFile and the tag value. The return value is iflOKAY on success, or an appropriate iflStatus error value on failure. The second overloaded form of this method is used by libraries that are passing along a variable calling sequence in _a_p through some wrapper layer. sssseeeettttPPPPaaaaggggeeee(((()))) virtual iflStatus setPage(const void* data, int x, int y, int z, int c, int nx, int ny, int nz, int nc) PPPPaaaaggggeeee 11118888 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) This virtual member function writes a page of image data from the image file. The _d_a_t_a argument specifies the address of the memory buffer containing the data to be written. The arguments _x,_y,_z,_n_x,_n_y and _n_z specify the origin and size of the desired page within the source image file. The caller must guarantee that _n_x,_n_y,_n_z and _n_c are the image's page size and that _x,_y,_z and _c are a multiple of the page size; no checking is done by the function. A successful call to sssseeeettttPPPPaaaaggggeeee() returns iflOKAY. If an error occurs, an iflStatus value is returned describing the error; in this case the contents of the file are undefined. The same MP safety issues apply here as for ggggeeeettttPPPPaaaaggggeeee() (see above). sssseeeettttSSSSccccaaaalllleeeeMMMMiiiinnnnMMMMaaaaxxxx(((()))) virtual iflStatus setScaleMinMax(double min, double max) Sets the minimum and maximum value to be used for scaling during color conversion on the current image in the image file. On successful completion, the function returns iflOKAY. On failure, the function returns an iflStatus indicating the reason for failure. sssseeeettttSSSSttttaaaattttMMMMiiiinnnnMMMMaaaaxxxx(((()))) virtual iflStatus setStatMinMax(double min, double max) Sets the file's notion of the range of values that occur in the current image in the image file. On successful completion, the function returns iflOKAY. On failure, the function returns an iflStatus indicating the reason for failure. sssseeeettttTTTTiiiilllleeee(((()))) iflStatus setTile(int x, int y, int z, int nx, int ny, int nz, const void *data, const iflConfig* config=NULL) This member function writes an arbitrary rectangular region from a memory buffer into the image file. The portions of the memory buffer corresponding to area outside the boundaries of the source file image are ignored. PPPPaaaaggggeeee 11119999 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) The arguments _x,_y,_z,_n_x,_n_y and _n_z specify the origin and size of the target tile within the destination image file, in the coordinate space indicated in the _c_o_n_f_i_g parameter. The _d_a_t_a argument specifies the address of the memory buffer containing the data to be written. The _c_o_n_f_i_g argument describes the configuration of the memory buffer, and its orientation also affects the interpretation of _x,_y,_z,_n_x,_n_y and _n_z, as described above. If defaulted, attributes of the buffer are assumed to match those of the image. A successful call to sssseeeettttTTTTiiiilllleeee() returns iflOKAY. If an error occurs, an iflStatus value is returned describing the error; in this case the contents of the file are undefined. Note that sssseeeettttTTTTiiiilllleeee() may need to make calls to the subclass's ggggeeeettttPPPPaaaaggggeeee() as well as setPage() in order to write a tile that is not aligned with the file's pages. SSSSEEEEEEEE AAAALLLLSSSSOOOO iflFormat(3), iflSize(3), iflFileDesc(3) PPPPaaaaggggeeee 22220000 
